본문으로 건너뛰기

SHIELD Mail 프록시 설정 가이드

문서 버전: 1.0
작성일: 2025-10-27
대상: 구축팀, 온프레미스 운영자

개요​

SHIELD Mail은 아웃바운드 트래픽을 프록시를 통해 관리할 수 있습니다. 이 문서는 온프레미스 환경에서 프록시 설정을 위한 빠른 시작 가이드입니다.

프록시 사용 목적​

  • 모든 외부 통신이 중앙 집중식 프록시를 통함
  • 내부 서비스 통신은 직접 연결로 최적화
  • 네트워크 정책 및 보안 감시 중앙화
  • 엔터프라이즈 프록시 요구사항 충족

빠른 설정 (3단계)​

1단계: Squid 프록시 배포​

# 1. Squid 프록시 배포
kubectl apply -f build/squid-proxy-deploy.yaml

# 2. 배포 확인
kubectl get pod -n dev -l app=squid-proxy
# 예상 결과: squid-proxy-XXXXX 1/1 Running

주요 리소스:

  • Deployment: squid-proxy (1 replica)
  • Service: squid-proxy (Port 3128)
  • ConfigMap: squid-config (프록시 설정)

2단계: SHIELD Mail 프록시 설정​

build/kube-deploy.yaml의 ConfigMap에 다음 환경변수를 추가합니다:

apiVersion: v1
kind: ConfigMap
metadata:
  name: shieldmail-config
  namespace: dev
data:
  # Go 컨테이너 프록시 설정
  HTTP_PROXY: "http://squid-proxy.dev.svc.cluster.local:3128"
  HTTPS_PROXY: "http://squid-proxy.dev.svc.cluster.local:3128"
  
  # 프록시 예외 목록 (클러스터 내부 통신은 프록시 우회)
  NO_PROXY: "localhost,127.0.0.1,.svc.cluster.local,.cluster.local,10.42.0.0/16,10.43.0.0/16,redis-sentinel-ha-headless.dev.svc.cluster.local,security365-rabbitmq-headless.dev.svc.cluster.local,elasticsearch-cluster-data.elasticsearch.svc.cluster.local"

  # JVM 컨테이너 프록시 설정
  JAVA_TOOL_OPTIONS: "-Dhttp.proxyHost=squid-proxy.dev.svc.cluster.local -Dhttp.proxyPort=3128 -Dhttps.proxyHost=squid-proxy.dev.svc.cluster.local -Dhttps.proxyPort=3128 -Dhttp.nonProxyHosts=localhost|127.0.0.1|*.svc.cluster.local|*.cluster.local|10.42.0.0/16"

💡 프록시 주소 변경: HTTP_PROXY, HTTPS_PROXY 값을 실제 프록시 주소로 변경하세요.

3단계: 배포 및 검증​

# 설정 적용
kubectl apply -f build/kube-deploy.yaml

# Pod 상태 확인
kubectl get pods -n dev -l app=shieldmail
# 예상 결과: shieldmail-0 3/3 Running

# 프록시 검증 로그 확인
kubectl logs -n dev shieldmail-0 -c shieldmail | grep proxy

프록시 동작 원리​

외부 통신 (프록시 경유)​

SHIELD Mail → HTTP_PROXY 확인
           → Squid Proxy (3128 포트)
           → 외부 서비스

대상:

  • 인터넷 API 호출
  • 클라우드 서비스 호출

내부 통신 (프록시 우회)​

SHIELD Mail → NO_PROXY 확인
           → 프록시 미사용
           → 클러스터 내부 서비스 직접 연결

대상:

  • Redis 캐시
  • RabbitMQ 메시지 큐
  • Elasticsearch
  • 클러스터 내부 서비스 (*.svc.cluster.local)

SMTP 통신​

중요: SMTP는 HTTP가 아니므로 프록시 설정과 무관합니다.

  • 메일 전송(25 포트)은 프록시 없이 직접 연결
  • 방화벽에서 SMTP(25 포트) 아웃바운드 별도 허용 필요

주요 설정 항목​

Go 컨테이너 (shieldmail)​

환경변수설명예시
HTTP_PROXYHTTP 프록시 주소http://squid-proxy:3128
HTTPS_PROXYHTTPS 프록시 주소http://squid-proxy:3128
NO_PROXY프록시 우회 대상localhost,.svc.cluster.local

프록시 인증이 필요한 경우:

HTTP_PROXY: "http://username:password@proxy.example.com:3128"
HTTPS_PROXY: "http://username:password@proxy.example.com:3128"

JVM 컨테이너 (shieldmail-pep, cloud-containerlinker)​

환경변수설명예시
JAVA_TOOL_OPTIONSJava 시스템 프로퍼티-Dhttp.proxyHost=...

프록시 인증이 필요한 경우:

JAVA_TOOL_OPTIONS: "-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=3128 -Dhttp.proxyUser=username -Dhttp.proxyPassword=password ..."

자동 프록시 검증​

중요: 각 서비스는 시작 시 프록시 환경변수가 설정된 경우 자동으로 프록시 연결을 검증합니다.

  • Go 컨테이너: HTTP_PROXY 설정 시 자동 프록시 테스트 실행
  • JVM 컨테이너: -Dhttp.proxyHost 설정 시 자동 프록시 테스트 실행
  • 로그에서 "proxy validation" 검색하여 결과 확인

검증 방법​

1. 환경변수 확인​

# Go 컨테이너
kubectl exec -n dev shieldmail-0 -c shieldmail -- env | grep -i proxy

# JVM 컨테이너
kubectl exec -n dev shieldmail-0 -c shieldmail-pep -- env | grep JAVA_TOOL_OPTIONS

2. 프록시 연결 테스트​

# Squid 포트 접근 확인
kubectl exec -n dev shieldmail-0 -c shieldmail -- nc -zv squid-proxy.dev.svc.cluster.local 3128

3. 프록시 동작 확인​

# 프록시 경유 로그 확인
kubectl logs -n dev shieldmail-0 -c shieldmail | grep -i "via header"

# 예상 결과
# Proxy validation - Via header: 1.1 squid-proxy-xxx

트러블슈팅​

문제: 프록시 연결 실패​

증상:

Failed to connect to proxy

해결:

  1. Squid Pod 상태 확인: kubectl get pod -n dev -l app=squid-proxy
  2. 프록시 포트 접근 확인: nc -zv squid-proxy 3128
  3. 환경변수 확인: env | grep HTTP_PROXY

문제: SMTP 전송 실패​

증상:

Connection timeout to mail.example.com:25

원인:

  • SMTP는 프록시를 사용하지 않는 raw TCP 연결
  • 네트워크 방화벽에서 25 포트 아웃바운드 차단 가능성

해결:

  • Azure NSG / 네트워크 방화벽에서 SMTP(25) 아웃바운드 허용
  • DNS 서버 정상 동작 확인

문제: JVM 컨테이너 /tmp 오류​

증상:

Read-only file system: /tmp

해결: StatefulSet의 볼륨 마운트 확인:

volumeMounts:
  - name: tmp
    mountPath: /tmp

체크리스트​

배포 전 확인 사항:

  • Squid 프록시 배포 완료 (1/1 Running)
  • ConfigMap에 프록시 환경변수 추가
  • NO_PROXY에 내부 서비스 포함
  • 네트워크 방화벽에서 SMTP(25) 아웃바운드 허용
  • SHIELD Mail Pod 재배포
  • 프록시 검증 로그 확인
  • 외부 API 호출 정상 동작 확인

상세 문서​

더 자세한 내용이 필요하신가요?

문서 버전: 1.0
최종 수정일: 2025-10-27